/*!
 * \file CpuHelper.hpp
 * \brief CPU操作辅助类，提供CPU核心数查询和线程绑定功能
 * 
 * \details 跨平台的CPU操作工具类，包括：
 *          - CPU核心数量查询
 *          - 线程到指定CPU核心的绑定
 *          - Windows、Linux、macOS多平台支持
 *          - 高性能计算场景的线程亲和性设置
 *          
 *          在高频交易和实时计算场景中，通过绑定线程到特定CPU核心
 *          可以减少上下文切换开销，提高程序性能和延迟稳定性。
 */
#pragma once
#include <thread>

/*!
 * \brief CPU操作辅助类
 * 
 * \details 提供跨平台的CPU相关操作功能，特点：
 *          - 静态方法设计，无需实例化
 *          - 自动检测CPU核心数量
 *          - 支持线程绑定到指定CPU核心
 *          - 跨平台兼容（Windows、Linux、macOS）
 *          - 错误处理和边界检查
 *          
 *          适用场景：
 *          - 高性能计算应用
 *          - 实时交易系统
 *          - 多线程并行处理
 *          - 延迟敏感的应用程序
 */
class CpuHelper
{
public:
	/*!
	 * \brief 获取CPU核心数量
	 * \return CPU核心数量
	 * 
	 * \details 使用std::thread::hardware_concurrency()获取系统CPU核心数，
	 *          采用静态变量缓存结果，避免重复查询的开销。
	 *          返回的是逻辑核心数（包括超线程）。
	 */
	static uint32_t get_cpu_cores()
	{
		static uint32_t cores = std::thread::hardware_concurrency();
		return cores;
	}

#ifdef _WIN32
#include <thread>
	/*!
	 * \brief 绑定当前线程到指定CPU核心（Windows版本）
	 * \param i CPU核心索引（从0开始）
	 * \return 成功返回true，失败返回false
	 * 
	 * \details Windows平台使用SetThreadAffinityMask API：
	 *          1. 检查核心索引是否有效
	 *          2. 获取当前线程句柄
	 *          3. 设置线程亲和性掩码
	 *          4. 返回操作结果
	 *          
	 *          注意：需要足够的权限才能设置线程亲和性
	 */
	static bool bind_core(uint32_t i)
	{
		uint32_t cores = get_cpu_cores();
		if (i >= cores)
			return false;

		HANDLE hThread = GetCurrentThread();
		DWORD_PTR mask = SetThreadAffinityMask(hThread, (DWORD_PTR)(1 << i));
		return (mask != 0);
	}
#elif defined(__linux__)
#include <pthread.h>
#include <sched.h>
#include <unistd.h>
#include <string.h>
	/*!
	 * \brief 绑定当前线程到指定CPU核心（Linux版本）
	 * \param i CPU核心索引（从0开始）
	 * \return 成功返回true，失败返回false
	 * 
	 * \details Linux平台使用pthread_setaffinity_np API：
	 *          1. 检查核心索引是否有效
	 *          2. 初始化CPU集合
	 *          3. 设置指定CPU到集合中
	 *          4. 应用CPU亲和性设置
	 *          
	 *          使用GNU扩展函数，需要_GNU_SOURCE宏定义
	 */
	static bool bind_core(uint32_t i)
	{
		int cores = get_cpu_cores();
		if (i >= cores)
			return false;

		cpu_set_t mask;
		CPU_ZERO(&mask);
		CPU_SET(i, &mask);
		return (pthread_setaffinity_np(pthread_self(), sizeof(mask), &mask) >= 0);
	}
#else
	/*!
	 * \brief 绑定当前线程到指定CPU核心（macOS和其他Unix系统版本）
	 * \param i CPU核心索引（从0开始，此参数在macOS下被忽略）
	 * \return 总是返回true（表示"成功"但实际未进行绑定）
	 * 
	 * \details macOS不直接支持线程CPU亲和性设置：
	 *          - macOS使用Grand Central Dispatch (GCD)进行线程管理
	 *          - 系统自动优化线程调度，不推荐手动设置亲和性
	 *          - 此实现返回true以保持接口一致性
	 *          - 实际未执行任何CPU绑定操作
	 *          
	 *          对于需要高性能的macOS应用，建议：
	 *          - 使用GCD的并发队列
	 *          - 利用QoS（Quality of Service）类别
	 *          - 让系统自动管理线程调度
	 */
	static bool bind_core(uint32_t i)
	{
		// On macOS, thread affinity is not directly supported
		// Return true to indicate "success" but no actual binding occurs
		return true;
	}
#endif
};